<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-GB" xml:lang="en-GB">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>uihelptask</title>
  <style>
  html {font-family: Hoefler Text, Palatino, Georgia, serif;
    color: #1a1a1a;
    background-color: #fdfdfd;}

  body {margin: 0 auto;
    max-width: 40em;
    padding-left: 15px;
    padding-right: 15px;
    padding-top: 5px;
    padding-bottom: 5px;
    hyphens: auto;
    overflow-wrap: break-word;
    text-rendering: optimizeLegibility;
    font-kerning: normal;
  }

  @media (max-width: 600px) {body {font-size: 0.9em;
    padding: 1em;}
    h1 {font-size: 1.8em;}
  }

  @media print {body {background-color: transparent;
    color: black;
    font-size: 12pt;}
    p, h2, h3 {	orphans: 3;
    widows: 3;}
    h2, h3, h4 {	page-break-after: avoid;}
  }

  header {display: none;}
  kbd {margin: 0px 0.1em;
    padding: 0.1em 0.6em;
    border-radius: 3px;
    border: 1px solid rgb(204, 204, 204);
    color: rgb(51, 51, 51);
    line-height: 1.4;
    font-family: Menlo, monospace;
    font-size: 11px;
    display: inline-block;
    box-shadow: 0px 1px 0px rgba(0,0,0,0.3);
    background-color: rgb(247, 247, 247);
    text-shadow: 0 1px 0 #fff;
  }
  kbd:hover {box-shadow: 0 1px 0 0.5px;}
  p {font-size: 18px;margin: 0.8em 0;line-height: 1.5;}
  a {color: #1a1a1a;}
  a:visited {color: #1a1a1a;}
  img {max-width: 100%;}
  h1, h2, h3, h4, h5, h6 {margin-top: 1.4em;}
  h5, h6 {font-size: 1em;
  font-style: italic;}
  h6 {font-weight: normal;}
  ol, ul {font-size: 18px;
    line-height: 1.2em;
    padding-left: 1.7em;
    margin-top: 1em;}
  li > ol, li > ul {margin-top: 0;}
  blockquote {margin: 1em 0 1em 1.7em;
    padding-left: 1em;
    border-left: 2px solid #e6e6e6;
    color: #606060;
    font-style: italic;}
  code {font-family: Fira Code, Menlo, Consolas, monospace;
    font-size: 14px;
    margin: 0;
    background-color: #F0F0F0;
    color:rgb(145, 16, 42);
  }
  pre {margin: 1em 0;
    overflow: auto;
  }
  pre code {padding: 0;
    overflow: visible;
    overflow-wrap: normal;
    background-color:transparent;
    color: black;
  }
  pre.smaller code {font-size: 60% !important; line-height: .75rem !important;}
  .sourceCode {background-color: transparent;
    overflow: visible;
  }
  hr {background-color: #1a1a1a;
    border: none;
    height: 1px;
    margin: 1em 0;
  }
  table {margin: 1em 0;
    border-collapse: collapse;
    width: 100%;
    overflow-x: auto;
    display: block;
    font-variant-numeric: lining-nums tabular-nums;
  }
  table caption {margin-bottom: 0.75em;}
  tbody {margin-top: 0.5em;
    border-top: 1px solid #1a1a1a;
    border-bottom: 1px solid #1a1a1a;
  }
  th {border-top: 1px solid #1a1a1a;
    padding: 0.25em 0.5em 0.25em 0.5em;
  }
  td {padding: 0.125em 0.5em 0.25em 0.5em;}
  header {margin-bottom: 4em;
    text-align: center;
  }
  #TOC li {list-style: none;}
  #TOC ul {padding-left: 1.3em;}
  #TOC > ul {padding-left: 0;}
  #TOC a:not(:hover) {text-decoration: none;}
  code{white-space: pre-wrap;}
  span.smallcaps{font-variant: small-caps;}
  span.underline{text-decoration: underline;}
  div.column{display: inline-block; vertical-align: top; width: 50%;}
  div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
  ul.task-list{list-style: none;}
  pre > code.sourceCode { white-space: pre; position: relative;}
  pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
  pre > code.sourceCode > span:empty { height: 1.2em; }
  .sourceCode { overflow: visible; }
  code.sourceCode > span { color: inherit; text-decoration: inherit; }
  div.sourceCode { margin: 2em 0; }
  pre.sourceCode { margin: 0; }
  @media screen {
  div.sourceCode { overflow: auto; background-color: #F0F0F0;}
  }
  @media print {
  pre > code.sourceCode { white-space: pre-wrap;}
  pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
  }
  pre.numberSource code
    { counter-reset: source-line 0; }
  pre.numberSource code > span
    { position: relative; left: -4em; counter-increment: source-line; }
  pre.numberSource code > span > a:first-child::before
    { content: counter(source-line);
      position: relative; left: -1em; text-align: right; vertical-align: baseline;
      border: none; display: inline-block;
      -webkit-touch-callout: none; -webkit-user-select: none;
      -khtml-user-select: none; -moz-user-select: none;
      -ms-user-select: none; user-select: none;
      padding: 0 4px; width: 4em;
      color: #aaaaaa;
    }
  pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
  @media screen {
  pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
  }
  code span.al { color: #ff0000; font-weight: bold; } /* Alert */
  code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
  code span.at { color: #7d9029; } /* Attribute */
  code span.bn { color: #40a070; } /* BaseN */
  code span.bu { color: #008000; } /* BuiltIn */
  code span.cf { color: #0044a3; font-weight: bold; } /* ControlFlow */
  code span.ch { color: #4070a0; } /* Char */
  code span.cn { color: #880000; } /* Constant */
  code span.co { color: #779097; font-style: italic; } /* Comment */
  code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
  code span.do { color: #ba2121; font-style: italic; } /* Documentation */
  code span.dt { color: #902000; } /* DataType */
  code span.dv { color: #40a070; } /* DecVal */
  code span.er { color: #ff0000; font-weight: bold; } /* Error */
  code span.fl { color: #40a070; } /* Float */
  code span.fu { color: #06287e; } /* Function */
  code span.im { color: #008000; font-weight: bold; } /* Import */
  code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
  code span.kw { color: #00338a; font-weight: bold; } /* Keyword */
  code span.op { color: #666666; } /* Operator */
  code span.ot { color: #007020; } /* Other */
  code span.pp { color: #bc7a00; } /* Preprocessor */
  code span.sc { color: #4070a0; } /* SpecialChar */
  code span.ss { color: #bb6688; } /* SpecialString */
  code span.st { color: #4070a0; } /* String */
  code span.va { color: #201f45; } /* Variable */
  code span.vs { color: #4070a0; } /* VerbatimString */
  code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
  .display.math{display: block; text-align: center; margin: 0.5rem auto;}
  </style>
</head>
<body>
<h1 id="optickas-two-experiment-modes">Opticka’s Two Experiment
Modes</h1>
<ol type="1">
<li><strong>Behavioural Task</strong> – a behavioural task uses a
<code>stateMachine</code> to construct a series of experiment states and
the transitions between them. It uses <code>StateInfo.m</code> files and
<code>userFunctions.m</code> files to specify the states and any
customised functions required. It can optionally use
<code>taskSequence</code>, <code>metaStimulus</code>,
<code>eyeTracker</code>, <code>IO</code>, and other manager classes to
control stimuli, variables, and hardware interaction.</li>
<li><strong>Method of Constants (MOC) Task</strong> – a MOC task is a
task where <strong>no</strong> behavioural control is required. It uses
<code>metaStimulus</code> and <code>taskSequence</code> to define a set
of stimuli and the variables that will drive unique trials repeated over
blocks.</li>
</ol>
<h2 id="basic-settings-see-below-for-more-details">Basic Settings (see
below for more details):</h2>
<ul>
<li><strong>Repeat Blocks</strong>: number of blocks to repeat.</li>
<li><strong>Random Algorithm</strong>: the randomisation algorithm used
by MATLAB’s rand functions.</li>
<li><strong>MOC Trial time</strong>: the time the stimulus is presented
for.</li>
<li><strong>MOC IT time</strong>: the time between trials.</li>
<li><strong>MOC IB time</strong>: the time between blocks.</li>
<li><strong>REAL Time</strong>: We can use two timing methods, when REAL
Time=ON then we use the PTB method <code>GetSecs</code> or the VBL to
measure time stamps and task time is based on these real time values.
When when REAL Time=OFF then we calculate how many frames a time
interval should contain and use ticks to measure time as each frame is
shown. REAL Time is essential for real experiments, ticks are more
useful for debugging where you can stop and step through carefully.</li>
</ul>
<h1 id="task-parameters">Task Parameters</h1>
<p>Opticka uses the <code>taskSequence</code> class to build the
stimulus randomisation. This class takes a series of <strong>independent
variables</strong> with values and builds the randomisation into
repeated blocks. The GUI does this using the <kbd>Ind. Variable
List</kbd> editor, but the underlying code looks like this
(<code>nBlocks</code> is <strong>Task Options &gt; Repeat
Blocks</strong> in the GUI):</p>
<div class="sourceCode" id="cb1"><pre
class="sourceCode matlab"><code class="sourceCode matlab"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co">% task sequence with 2 blocks</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="va">task</span> <span class="op">=</span> <span class="va">taskSequence</span>(<span class="ss">&#39;nBlocks&#39;</span><span class="op">,</span> <span class="fl">2</span>)<span class="op">;</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="co">% first variable: 3 angles that will be applied to stimuli 1 &amp; 2</span></span>
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">1</span>).<span class="va">name</span> <span class="op">=</span> <span class="ss">&#39;angle&#39;</span><span class="op">;</span></span>
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">1</span>).<span class="va">values</span> <span class="op">=</span> [<span class="op">-</span><span class="fl">25</span> <span class="fl">0</span> <span class="fl">25</span>]<span class="op">;</span></span>
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">1</span>).<span class="va">stimulus</span> <span class="op">=</span> [<span class="fl">1</span> <span class="fl">2</span>]<span class="op">;</span></span>
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a><span class="co">% second variable: 2 colours that will be applied to stimulus 3 only</span></span>
<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">2</span>).<span class="va">name</span> <span class="op">=</span> <span class="ss">&#39;colour&#39;</span><span class="op">;</span></span>
<span id="cb1-11"><a href="#cb1-11" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">2</span>).<span class="va">values</span> <span class="op">=</span> {[<span class="fl">1</span> <span class="fl">0</span> <span class="fl">0</span>]<span class="op">,</span> [<span class="fl">0</span> <span class="fl">1</span> <span class="fl">0</span>]}<span class="op">;</span></span>
<span id="cb1-12"><a href="#cb1-12" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">nVar</span>(<span class="fl">2</span>).<span class="va">stimulus</span> <span class="op">=</span> <span class="fl">3</span><span class="op">;</span></span>
<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a><span class="va">randomiseTask</span>(<span class="va">task</span>)<span class="op">;</span></span></code></pre></div>
<p>Independent variables can be any stimulus parameter
(<code>size</code>,<code>angle</code>,<code>xPosition</code> etc.) that
can be assigned to that stimulus. There are some magic variables like
<code>xyPosition</code> that allows you to pass both the X and Y
position in a single variable value.</p>
<p><code>randomiseTask(task)</code> will generate the randomisation
table like so (3 angles x 2 colours per block = <strong>6</strong>
conditions; 2 block = <strong>12</strong> total trials):</p>
<table>
<thead>
<tr>
<th>Angle</th>
<th>Colour</th>
<th style="text-align: left;">Index</th>
<th style="text-align: left;">IdxAngle</th>
<th>IdxColour</th>
<th style="text-align: left;">Trial Factor</th>
<th style="text-align: left;">Block Factor</th>
</tr>
</thead>
<tbody>
<tr>
<td>-25</td>
<td>1 0 0</td>
<td style="text-align: left;">1</td>
<td style="text-align: left;">1</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>0</td>
<td>1 0 0</td>
<td style="text-align: left;">3</td>
<td style="text-align: left;">2</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>25</td>
<td>0 1 0</td>
<td style="text-align: left;">6</td>
<td style="text-align: left;">3</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>25</td>
<td>1 0 0</td>
<td style="text-align: left;">5</td>
<td style="text-align: left;">3</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>-25</td>
<td>0 1 0</td>
<td style="text-align: left;">2</td>
<td style="text-align: left;">1</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>0</td>
<td>0 1 0</td>
<td style="text-align: left;">4</td>
<td style="text-align: left;">2</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>-25</td>
<td>0 1 0</td>
<td style="text-align: left;">2</td>
<td style="text-align: left;">1</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>0</td>
<td>0 1 0</td>
<td style="text-align: left;">4</td>
<td style="text-align: left;">2</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>-25</td>
<td>1 0 0</td>
<td style="text-align: left;">1</td>
<td style="text-align: left;">1</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>25</td>
<td>0 1 0</td>
<td style="text-align: left;">6</td>
<td style="text-align: left;">3</td>
<td>2</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>0</td>
<td>1 0 0</td>
<td style="text-align: left;">3</td>
<td style="text-align: left;">2</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
<tr>
<td>25</td>
<td>1 0 0</td>
<td style="text-align: left;">5</td>
<td style="text-align: left;">3</td>
<td>1</td>
<td style="text-align: left;">‘none’</td>
<td style="text-align: left;">‘none’</td>
</tr>
</tbody>
</table>
<p>Opticka’s task function can then use this table to assign variables
on each trial to the defined stimuli and generate strobed words to send
to external equipment. See core protocols like
<code>OrientationTuning.mat</code> to get a working example of this in
action.</p>
<h2 id="block-level-and-trial-level-factors">Block-Level and Trial-Level
Factors</h2>
<p>In addition, you can specify <em>independent</em> block and trial
factors. For example if we set</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode matlab"><code class="sourceCode matlab"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">blockVar</span>.<span class="va">values</span><span class="op">=</span>{<span class="ss">&#39;A&#39;</span><span class="op">,</span><span class="ss">&#39;B&#39;</span>}<span class="op">;</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">blockVar</span>.<span class="va">probability</span> <span class="op">=</span> [<span class="fl">0.6</span> <span class="fl">0.4</span>]<span class="op">;</span></span></code></pre></div>
<p>Then for each block we assign either <code>A</code> or <code>B</code>
with a 60:40% probability. Trial-level factors are specified in the same
way, but for each trial independently of the blocks.</p>
<div class="sourceCode" id="cb3"><pre
class="sourceCode matlab"><code class="sourceCode matlab"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">trialVar</span>.<span class="va">values</span><span class="op">=</span>{<span class="ss">&#39;Y&#39;</span><span class="op">,</span><span class="ss">&#39;Z&#39;</span>}<span class="op">;</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="va">task</span>.<span class="va">trialVar</span>.<span class="va">probability</span> <span class="op">=</span> [<span class="fl">0.5</span> <span class="fl">0.5</span>]<span class="op">;</span></span></code></pre></div>
<table>
<thead>
<tr>
<th>Angle</th>
<th>Colour</th>
<th style="text-align: left;">Index</th>
<th style="text-align: left;">IdxAngle</th>
<th>IdxColour</th>
<th style="text-align: left;">Trial Factor</th>
<th style="text-align: left;">Block Factor</th>
</tr>
</thead>
<tbody>
<tr>
<td>-25</td>
<td>1 0 0</td>
<td style="text-align: left;">1</td>
<td style="text-align: left;">1</td>
<td>1</td>
<td style="text-align: left;">Z</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>0</td>
<td>1 0 0</td>
<td style="text-align: left;">3</td>
<td style="text-align: left;">2</td>
<td>1</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>25</td>
<td>0 1 0</td>
<td style="text-align: left;">6</td>
<td style="text-align: left;">3</td>
<td>2</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>25</td>
<td>1 0 0</td>
<td style="text-align: left;">5</td>
<td style="text-align: left;">3</td>
<td>1</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>-25</td>
<td>0 1 0</td>
<td style="text-align: left;">2</td>
<td style="text-align: left;">1</td>
<td>2</td>
<td style="text-align: left;">Z</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>0</td>
<td>0 1 0</td>
<td style="text-align: left;">4</td>
<td style="text-align: left;">2</td>
<td>2</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">A</td>
</tr>
<tr>
<td>-25</td>
<td>0 1 0</td>
<td style="text-align: left;">2</td>
<td style="text-align: left;">1</td>
<td>2</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">B</td>
</tr>
<tr>
<td>0</td>
<td>0 1 0</td>
<td style="text-align: left;">4</td>
<td style="text-align: left;">2</td>
<td>2</td>
<td style="text-align: left;">Z</td>
<td style="text-align: left;">B</td>
</tr>
<tr>
<td>-25</td>
<td>1 0 0</td>
<td style="text-align: left;">1</td>
<td style="text-align: left;">1</td>
<td>1</td>
<td style="text-align: left;">Z</td>
<td style="text-align: left;">B</td>
</tr>
<tr>
<td>25</td>
<td>0 1 0</td>
<td style="text-align: left;">6</td>
<td style="text-align: left;">3</td>
<td>2</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">B</td>
</tr>
<tr>
<td>0</td>
<td>1 0 0</td>
<td style="text-align: left;">3</td>
<td style="text-align: left;">2</td>
<td>1</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">B</td>
</tr>
<tr>
<td>25</td>
<td>1 0 0</td>
<td style="text-align: left;">5</td>
<td style="text-align: left;">3</td>
<td>1</td>
<td style="text-align: left;">Y</td>
<td style="text-align: left;">B</td>
</tr>
</tbody>
</table>
<p>Trial- and Block-factors can be used to drive state machine functions
if you need it (<code>Saccadic_Doublestep.mat</code> is an example
protocol).</p>
</body>
</html>
